<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang xml:lang>
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <title>Alpine Term</title>
  <style type="text/css">
      code{white-space: pre-wrap;}
      span.smallcaps{font-variant: small-caps;}
      span.underline{text-decoration: underline;}
      div.column{display: inline-block; vertical-align: top; width: 50%;}
  </style>
  <style type="text/css">
a.sourceLine { display: inline-block; line-height: 1.25; }
a.sourceLine { pointer-events: none; color: inherit; text-decoration: inherit; }
a.sourceLine:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode { white-space: pre; position: relative; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
code.sourceCode { white-space: pre-wrap; }
a.sourceLine { text-indent: -1em; padding-left: 1em; }
}
pre.numberSource a.sourceLine
  { position: relative; left: -4em; }
pre.numberSource a.sourceLine::before
  { content: attr(title);
    position: relative; left: -1em; text-align: right; vertical-align: baseline;
    border: none; pointer-events: all; display: inline-block;
    -webkit-touch-callout: none; -webkit-user-select: none;
    -khtml-user-select: none; -moz-user-select: none;
    -ms-user-select: none; user-select: none;
    padding: 0 4px; width: 4em;
    color: #aaaaaa;
  }
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa;  padding-left: 4px; }
div.sourceCode
  {  }
@media screen {
a.sourceLine::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code span.at { color: #7d9029; } /* Attribute */
code span.bn { color: #40a070; } /* BaseN */
code span.bu { } /* BuiltIn */
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code span.ch { color: #4070a0; } /* Char */
code span.cn { color: #880000; } /* Constant */
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
code span.dt { color: #902000; } /* DataType */
code span.dv { color: #40a070; } /* DecVal */
code span.er { color: #ff0000; font-weight: bold; } /* Error */
code span.ex { } /* Extension */
code span.fl { color: #40a070; } /* Float */
code span.fu { color: #06287e; } /* Function */
code span.im { } /* Import */
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
code span.op { color: #666666; } /* Operator */
code span.ot { color: #007020; } /* Other */
code span.pp { color: #bc7a00; } /* Preprocessor */
code span.sc { color: #4070a0; } /* SpecialChar */
code span.ss { color: #bb6688; } /* SpecialString */
code span.st { color: #4070a0; } /* String */
code span.va { color: #19177c; } /* Variable */
code span.vs { color: #4070a0; } /* VerbatimString */
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
  </style>
  <style type="text/css">
html {
font-size: 100%;
overflow-y: scroll;
-webkit-text-size-adjust: 100%;
-ms-text-size-adjust: 100%;
}
body {
color: #444;
font-family: Georgia, Palatino, 'Palatino Linotype', Times, 'Times New Roman', serif;
font-size: 12px;
line-height: 1.7;
padding: 1em;
margin: auto;
max-width: 42em;
background: #fefefe;
}
a {
color: #0645ad;
text-decoration: none;
}
a:visited {
color: #0b0080;
}
a:hover {
color: #06e;
}
a:active {
color: #faa700;
}
a:focus {
outline: thin dotted;
}
*::-moz-selection {
background: rgba(255, 255, 0, 0.3);
color: #000;
}
*::selection {
background: rgba(255, 255, 0, 0.3);
color: #000;
}
a::-moz-selection {
background: rgba(255, 255, 0, 0.3);
color: #0645ad;
}
a::selection {
background: rgba(255, 255, 0, 0.3);
color: #0645ad;
}
p {
margin: 1em 0;
}
img {
max-width: 100%;
}
h1, h2, h3, h4, h5, h6 {
color: #111;
line-height: 125%;
margin-top: 2em;
font-weight: normal;
}
h4, h5, h6 {
font-weight: bold;
}
h1 {
font-size: 2.5em;
}
h2 {
font-size: 2em;
}
h3 {
font-size: 1.5em;
}
h4 {
font-size: 1.2em;
}
h5 {
font-size: 1em;
}
h6 {
font-size: 0.9em;
}
blockquote {
color: #666666;
margin: 0;
padding-left: 3em;
border-left: 0.5em #EEE solid;
}
hr {
display: block;
height: 2px;
border: 0;
border-top: 1px solid #aaa;
border-bottom: 1px solid #eee;
margin: 1em 0;
padding: 0;
}
pre, code, kbd, samp {
color: #000;
font-family: monospace, monospace;
_font-family: 'courier new', monospace;
font-size: 0.98em;
}
pre {
white-space: pre;
white-space: pre-wrap;
word-wrap: break-word;
}
b, strong {
font-weight: bold;
}
dfn {
font-style: italic;
}
ins {
background: #ff9;
color: #000;
text-decoration: none;
}
mark {
background: #ff0;
color: #000;
font-style: italic;
font-weight: bold;
}
sub, sup {
font-size: 75%;
line-height: 0;
position: relative;
vertical-align: baseline;
}
sup {
top: -0.5em;
}
sub {
bottom: -0.25em;
}
ul, ol {
margin: 1em 0;
padding: 0 0 0 2em;
}
li p:last-child {
margin-bottom: 0;
}
ul ul, ol ol {
margin: .3em 0;
}
dl {
margin-bottom: 1em;
}
dt {
font-weight: bold;
margin-bottom: .8em;
}
dd {
margin: 0 0 .8em 2em;
}
dd:last-child {
margin-bottom: 0;
}
img {
border: 0;
-ms-interpolation-mode: bicubic;
vertical-align: middle;
}
figure {
display: block;
text-align: center;
margin: 1em 0;
}
figure img {
border: none;
margin: 0 auto;
}
figcaption {
font-size: 0.8em;
font-style: italic;
margin: 0 0 .8em;
}
table {
margin-bottom: 2em;
border-bottom: 1px solid #ddd;
border-right: 1px solid #ddd;
border-spacing: 0;
border-collapse: collapse;
}
table th {
padding: .2em 1em;
background-color: #eee;
border-top: 1px solid #ddd;
border-left: 1px solid #ddd;
}
table td {
padding: .2em 1em;
border-top: 1px solid #ddd;
border-left: 1px solid #ddd;
vertical-align: top;
}
.author {
font-size: 1.2em;
text-align: center;
}
@media only screen and (min-width: 480px) {
body {
font-size: 14px;
}
}
@media only screen and (min-width: 768px) {
body {
font-size: 16px;
}
}
@media print {
* {
background: transparent !important;
color: black !important;
filter: none !important;
-ms-filter: none !important;
}
body {
font-size: 12pt;
max-width: 100%;
}
a, a:visited {
text-decoration: underline;
}
hr {
height: 1px;
border: 0;
border-bottom: 1px solid black;
}
a[href]:after {
content: " (" attr(href) ")";
}
abbr[title]:after {
content: " (" attr(title) ")";
}
.ir a:after, a[href^="javascript:"]:after, a[href^="#"]:after {
content: "";
}
pre, blockquote {
border: 1px solid #999;
padding-right: 1em;
page-break-inside: avoid;
}
tr, img {
page-break-inside: avoid;
}
img {
max-width: 100% !important;
}
@page :left {
margin: 15mm 20mm 15mm 10mm;
}
@page :right {
margin: 15mm 10mm 15mm 20mm;
}
p, h2, h3 {
orphans: 3;
widows: 3;
}
h2, h3 {
page-break-after: avoid;
}
}
</style>
</head>
<body>
<header id="title-block-header">
<h1 class="title">Alpine Term</h1>
</header>
<p>Alpine Term, aka Alpine Linux Terminal, is a virtual machine running the <a href="https://alpinelinux.org">Alpine Linux</a> — a security-oriented, lightweight Linux distribution based on musl libc and busybox.</p>
<p>Application does not use KVM and should work on any rootless device running Android 7.0 or higher. Here are the recommended minimal system properties:</p>
<ul>
<li>2 GHz CPU</li>
<li>2 GB RAM</li>
<li>6 GB disk space on internal storage</li>
</ul>
<p>If your hardware properties do not meet these ones, you may observe issues during installation or at runtime.</p>
<p>This application is general-purpose and you are limited only by environment isolation and performance.</p>
<hr />
<h2 id="user-guide">User Guide</h2>
<p>Table of contents:</p>
<ul>
<li><a href="#user-interface">User interface</a>
<ul>
<li><a href="#terminal">Terminal</a></li>
<li><a href="#context-menu">Context menu</a></li>
<li><a href="#navigation-drawer">Navigation drawer</a></li>
<li><a href="#notification">Notification</a></li>
<li><a href="#extra-keys-row">Extra keys row</a></li>
<li><a href="#text-input-field">Text input field</a></li>
</ul></li>
<li><a href="#keyboard">Keyboard</a>
<ul>
<li><a href="#touch-keyboard-shortcuts">Touch keyboard shortcuts</a></li>
<li><a href="#hardware-keyboard-shortcuts">Hardware keyboard shortcuts</a></li>
</ul></li>
<li><a href="#getting-started">Getting started</a>
<ul>
<li><a href="#qemu-monitor">QEMU monitor</a></li>
<li><a href="#shell">Shell</a></li>
<li><a href="#using-custom-disk-images">Using custom disk images</a></li>
<li><a href="#sharing-files-between-host-and-vm">Sharing files between host and VM</a></li>
<li><a href="#shutting-down-the-vm">Shutting down the VM</a></li>
</ul></li>
</ul>
<hr />
<h3 id="user-interface">User interface</h3>
<h4 id="terminal">Terminal</h4>
<p>The application emulates a subset of the X Window System (xterm) terminal with TrueColor support. Its capabilities should be enough for most of the available command line programs.</p>
<p><span style="display:block;text-align:center"> <img alt="QEMU session screenshot" src="" style="width:90%;max-width:700px;"> </span></p>
<p>As a connection to the virtual machine is done over serial line, a proper terminal window handshake is not possible. As a result, the virtual machine is not aware of the current state of the terminal emulator. If there is a window size mismatch between terminal emulator and virtual machine, you may observe visual glitches such as displaced or disappeared text when using certain programs.</p>
<p>Use utility ‘resize’ to make sure that the console size matches the size of the screen. If the terminal was messed up, use the utility ‘reset’ which will clean screen and reset the terminal to initial state.</p>
<p>The terminal is sensitive to taps and gestures. For example, pinch-zooming will change the font size and short tap will act as a mouse click. Long tap will toggle a text selection and the <a href="#context-menu">context menu</a>. By swiping rightwards, a <a href="#navigation-drawer">navigation drawer</a> will be revealed.</p>
<h4 id="context-menu">Context menu</h4>
<p>The context menu can be shown by long pressing anywhere on the terminal. It provides menu entries for:</p>
<ul>
<li>Opening VNC connection. Available only if <a href="https://play.google.com/store/apps/details?id=com.realvnc.viewer.android">RealVNC Viewer</a> is installed.</li>
<li>Copying or pasting text from clipboard.</li>
<li>Showing this help page.</li>
<li>Opening URL selector dialog.</li>
<li>Sharing text from the terminal to other apps.</li>
<li>Resetting the terminal state if it got messed up.</li>
<li>Changing a color scheme of the terminal.</li>
<li>Check box to control whether bell characters should be ignored.</li>
</ul>
<h4 id="navigation-drawer">Navigation drawer</h4>
<p>The navigation drawer is revealed by swiping inwards from the left part of screen.</p>
<p><span style="display:block;text-align:center"> <img alt="Navigation drawer screenshot" src="" style="width:90%;max-width:700px;"> </span></p>
<p>It contains few additional elements:</p>
<ol type="1">
<li>The list of sessions: the first one is <a href="#qemu-monitor">QEMU monitor</a> and the last four sessions are serial consoles (ttyS1-ttyS3). Click on a session to open.</li>
<li>The button to toggle visibility of a touch keyboard. <br>Long press will toggle the <a href="#extra-keys-row">extra keys row</a> (3).</li>
</ol>
<h4 id="notification">Notification</h4>
<p>While Alpine Term is running, it displays a notification which can be expanded by a pinch-zooming or a single-finger glide gestures to expose the action for toggling wake lock to prevent device’s CPU going into sleep mode.</p>
<p><span style="display:block;text-align:center"> <img alt="Notification screenshot" src="" style="width:90%;max-width:700px;"> </span></p>
<p>Clicking on the notification will open the current terminal session.</p>
<h4 id="extra-keys-row">Extra keys row</h4>
<p><span style="display:block;text-align:center"> <img alt="Extra keys row screenshot" src="" style="width:90%;max-width:700px;"> </span></p>
<p>Alpine Term provides a row, which contains some keys frequently used to interact with the command line. It can be toggled by either a long press on the keyboard button located on the <a href="#navigation-drawer">drawer</a> or by <strong>Volume Up+Q</strong> and <strong>Volume Up+K</strong> key combinations.</p>
<p>Swiping upwards certain keys will expose the alternate ones. Particularly:</p>
<ul>
<li><code>-</code> will show a key for <code>_</code></li>
<li><code>|</code> will show a key for <code>&amp;</code></li>
</ul>
<p>Swiping the extra keys row leftwards will reveal the <a href="#text-input-field">text input field</a>.</p>
<h4 id="text-input-field">Text input field</h4>
<p><span style="display:block;text-align:center"> <img alt="Text input field screenshot" src="" style="width:90%;max-width:700px;"> </span></p>
<p>The terminal does not support the advanced features of the touch keyboards like a predictive input or swipe typing. As a workaround, the application provides a special text input field where all these features work correctly.</p>
<hr />
<h3 id="keyboard">Keyboard</h3>
<h4 id="touch-keyboard-shortcuts">Touch keyboard shortcuts</h4>
<p><strong>Volume Down</strong> button emulates <strong>Ctrl</strong> key which can be combined with others to request a special action from command line tools. Common key combinations are:</p>
<ul>
<li><strong>Ctrl+A</strong> → Move cursor to the beginning of line</li>
<li><strong>Ctrl+C</strong> → Interrupt the current process with SIGINT</li>
<li><strong>Ctrl+D</strong> → Send end-of-file to the standard input</li>
<li><strong>Ctrl+E</strong> → Move cursor to the end of line</li>
<li><strong>Ctrl+K</strong> → Delete text from cursor to the end of line</li>
<li><strong>Ctrl+L</strong> → Clear the terminal</li>
<li><strong>Ctrl+Z</strong> → Suspend the current process with SIGTSTP</li>
</ul>
<p><strong>Volume Up</strong> key is used to produce certain input on the following combinations:</p>
<ul>
<li><strong>Volume Up+.</strong> → Ctrl+\ (SIGQUIT)</li>
<li><strong>Volume Up+1</strong> → F1 (and <strong>Volume Up+2</strong> → F2, etc)</li>
<li><strong>Volume Up+0</strong> → F10</li>
<li><strong>Volume Up+A</strong> → Left arrow key</li>
<li><strong>Volume Up+B</strong> → Alt+B, back a word (if using readline)</li>
<li><strong>Volume Up+D</strong> → Right arrow key</li>
<li><strong>Volume Up+E</strong> → Escape key</li>
<li><strong>Volume Up+F</strong> → Alt+F, forward a word (if using readline)</li>
<li><strong>Volume Up+H</strong> → ~ (the tilde character)</li>
<li><strong>Volume Up+K</strong> → Alias for <strong>Volume Up+Q</strong></li>
<li><strong>Volume Up+L</strong> → | (the pipe character)</li>
<li><strong>Volume Up+N</strong> → Page Down</li>
<li><strong>Volume Up+P</strong> → Page Up</li>
<li><strong>Volume Up+Q</strong> → Toggle extra keys row</li>
<li><strong>Volume Up+S</strong> → Down arrow key</li>
<li><strong>Volume Up+T</strong> → Tab key</li>
<li><strong>Volume Up+U</strong> → _ (the underscore character)</li>
<li><strong>Volume Up+V</strong> → Show the volume control</li>
<li><strong>Volume Up+W</strong> → Up arrow key</li>
<li><strong>Volume Up+X</strong> → Alt+X</li>
</ul>
<p>Note that <strong>Volume Up</strong> does not represent an <strong>Alt</strong> key even though it is able to emulate some its combinations.</p>
<h4 id="hardware-keyboard-shortcuts">Hardware keyboard shortcuts</h4>
<p>These keys in combination with <strong>Ctrl+Alt</strong> will trigger certain actions of Alpine Term when using a hardware keyboard:</p>
<ul>
<li><strong>+/-</strong> → Adjust text size</li>
<li><strong>1-5</strong> → Go to the session with specified number</li>
<li><strong>M</strong> → Show the <a href="#context-menu">context menu</a></li>
<li><strong>N</strong> → Switch to the next session</li>
<li><strong>P</strong> → Switch to the previous session</li>
<li><strong>U</strong> → Open URL selector</li>
<li><strong>V</strong> → Paste clipboard</li>
<li><strong>Left arrow</strong> → Close drawer</li>
<li><strong>Right arrow</strong> → Open drawer</li>
<li><strong>Down arrow</strong> → Alias for <strong>N</strong></li>
<li><strong>Up arrow</strong> → Alias for <strong>P</strong></li>
</ul>
<hr />
<h3 id="getting-started">Getting started</h3>
<h4 id="qemu-monitor">QEMU monitor</h4>
<p>QEMU monitor is instrument for controlling the state of the virtual machine. Its console can be accessed through the first tab on the <a href="#navigation-drawer">navigation drawer</a>.</p>
<p><span style="display:block;text-align:center"> <img alt="QEMU monitor screenshot" src="" style="width:90%;max-width:700px;"> </span></p>
<h5 id="list-of-common-monitor-commands">List of common monitor commands</h5>
<table>
<colgroup>
<col style="width: 59%"></col>
<col style="width: 40%"></col>
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Command</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;"><code>help</code></td>
<td style="text-align: left;">Show a full list of available commands. Not all of them are applicable to Alpine Term QEMU instance.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>help &lt;command&gt;</code></td>
<td style="text-align: left;">Show help for a specific command.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>stop</code></td>
<td style="text-align: left;">Pause emulation.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>cont</code></td>
<td style="text-align: left;">Resume emulation.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>quit</code></td>
<td style="text-align: left;">Terminate QEMU instance.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>sendkey &lt;key&gt;</code></td>
<td style="text-align: left;">Send key (combination) to the virtual machine. For example: ‘ctrl-alt-delete’.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>system_powerdown</code></td>
<td style="text-align: left;">Send ACPI request to the operating system to shut down.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>system_reset</code></td>
<td style="text-align: left;">Reset the system (reboot).</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>savevm &lt;name&gt;</code></td>
<td style="text-align: left;">Save a VM snapshot with the specified name. Unmount /mnt/share before using this command.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>loadvm &lt;name&gt;</code></td>
<td style="text-align: left;">Load a VM snapshot with the specified name.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>delvm &lt;name&gt;</code></td>
<td style="text-align: left;">Delete a VM snapshot with the specified name.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>set_link vmnic0 off</code></td>
<td style="text-align: left;">Disable network access.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>set_link vmnic0 on</code></td>
<td style="text-align: left;">Enable network access.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>hostfwd_add tcp::10022-:22</code></td>
<td style="text-align: left;">Redirect TCP connections from 0.0.0.0:10022 on host to guest port 22.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>hostfwd_remove tcp::10022</code></td>
<td style="text-align: left;">Remove port forwarding for 0.0.0.0:10022.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>nbd_server_add [-w] &lt;dev id&gt; [name]</code></td>
<td style="text-align: left;">Export a block device with specified ID over NBD. Optionally enable write access (-w) and assign a name.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>nbd_server_remove [-f] &lt;name&gt;</code></td>
<td style="text-align: left;">Remove NBD export with the specified name.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>nbd_server_start 0.0.0.0:8500</code></td>
<td style="text-align: left;">Start the NBD server listening on 0.0.0.0:8500.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>nbd_server_stop</code></td>
<td style="text-align: left;">Stop the NBD server.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>screendump &lt;file.ppm&gt;</code></td>
<td style="text-align: left;">Create a PPM screenshot of the display and save to the specified file.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>change vnc 127.0.0.1:1</code></td>
<td style="text-align: left;">Start the VNC server on 127.0.0.1:5901.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>change vnc 127.0.0.1:1,password</code></td>
<td style="text-align: left;">Start the VNC server on 127.0.0.1:5901 with password authentication.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>change vnc none</code></td>
<td style="text-align: left;">Stop the VNC server.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>change vnc password</code></td>
<td style="text-align: left;">Set the VNC password.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>dump-guest-memory &lt;file&gt;</code></td>
<td style="text-align: left;">Dump memory of the virtual machine into file.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>gdbserver tcp::4444</code></td>
<td style="text-align: left;">Start the GDB server listening on TCP 0.0.0.0:4444.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>gdbserver none</code></td>
<td style="text-align: left;">Stop the GDB server.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>info block</code></td>
<td style="text-align: left;">Show available block devices.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>info block-jobs</code></td>
<td style="text-align: left;">Show information about pending jobs for block devices.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>info pci</code></td>
<td style="text-align: left;">Show information about PCI devices.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>info registers</code></td>
<td style="text-align: left;">Show current values of CPU registers.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>info snapshots</code></td>
<td style="text-align: left;">Show available VM snapshots.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>info usernet</code></td>
<td style="text-align: left;">Show information about port forwardings and network connections.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>info vnc</code></td>
<td style="text-align: left;">Show information about VNC server state.</td>
</tr>
</tbody>
</table>
<p>QEMU monitor console supports TAB completion. Use this feature to get hints on command arguments.</p>
<h5 id="list-of-device-ids">List of device IDs</h5>
<table>
<thead>
<tr class="header">
<th style="text-align: left;">Device</th>
<th style="text-align: left;">ID</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">Primary CD-ROM block</td>
<td style="text-align: left;"><code>cd0</code></td>
</tr>
<tr class="even">
<td style="text-align: left;">Primary CD-ROM device</td>
<td style="text-align: left;"><code>scsi-cd0</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;">Secondary CD-ROM block</td>
<td style="text-align: left;"><code>cd1</code></td>
</tr>
<tr class="even">
<td style="text-align: left;">Secondary CD-ROM device</td>
<td style="text-align: left;"><code>scsi-cd1</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;">Primary HDD block</td>
<td style="text-align: left;"><code>hd0</code></td>
</tr>
<tr class="even">
<td style="text-align: left;">Primary HDD device</td>
<td style="text-align: left;"><code>scsi-hd0</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;">Secondary HDD block</td>
<td style="text-align: left;"><code>hd1</code></td>
</tr>
<tr class="even">
<td style="text-align: left;">Secondary HDD device</td>
<td style="text-align: left;"><code>scsi-hd1</code></td>
</tr>
<tr class="odd">
<td style="text-align: left;">Network interface card</td>
<td style="text-align: left;"><code>vmnic0</code></td>
</tr>
</tbody>
</table>
<h5 id="limiting-ram-usage">Limiting RAM usage</h5>
<p>You can limit RAM usage by configuring VirtIO Balloon device through QEMU monitor. See an example below how to limit memory usage to 350 MiB:</p>
<pre><code>balloon 350</code></pre>
<p>If guest operating system uses less memory than specified value, QEMU will de-allocate host RAM and update visible memory size for the virtual machine. In other cases virtual machine may not release used memory or do that partially.</p>
<p>Some kernels or custom operating systems may not support this feature.</p>
<h5 id="backing-up-the-hdd-image">Backing up the HDD image</h5>
<p>Use QEMU monitor to back up the operating system image. You can do this by executing the next command:</p>
<pre><code>drive_backup -f -c hd0 /sdcard/backup.qcow2 qcow2</code></pre>
<p>This command will copy the data into the new compressed (option ‘-c’) QCOW2 image ready for reuse. You can continue to use the virtual machine during the backup process. Progress can be tracked by this command:</p>
<pre><code>info block-jobs</code></pre>
<p>After finishing you can get your image in the Alpine Term private directory on <a href="#sharing-files-between-host-and-vm">shared storage</a>.</p>
<h5 id="restoring-the-hdd-image">Restoring the HDD image</h5>
<p>The restoring operation is quite complicated as you cannot have direct access to the runtime directory of Alpine Term. However, you can use trick with the ‘drive_backup’ command to overwrite the original HDD image.</p>
<div class="sourceCode" id="cb4" data-startFrom="1"><pre class="sourceCode numberSource numberLines"><code class="sourceCode"><a class="sourceLine" id="cb4-1" title="1"># First, reset and stop the virtual machine:</a>
<a class="sourceLine" id="cb4-2" title="2">system_reset</a>
<a class="sourceLine" id="cb4-3" title="3">stop</a>
<a class="sourceLine" id="cb4-4" title="4"></a>
<a class="sourceLine" id="cb4-5" title="5"># Check the path where the original image is being stored:</a>
<a class="sourceLine" id="cb4-6" title="6">info block</a>
<a class="sourceLine" id="cb4-7" title="7"></a>
<a class="sourceLine" id="cb4-8" title="8"># Here it will be assumed that its path is</a>
<a class="sourceLine" id="cb4-9" title="9"># /data/user/0/alpine.term/files/run/alpine-linux-hdd.qcow2</a>
<a class="sourceLine" id="cb4-10" title="10"></a>
<a class="sourceLine" id="cb4-11" title="11"># Remove the primary HDD:</a>
<a class="sourceLine" id="cb4-12" title="12">drive_del hd0</a>
<a class="sourceLine" id="cb4-13" title="13">device_del scsi-hd0</a>
<a class="sourceLine" id="cb4-14" title="14"></a>
<a class="sourceLine" id="cb4-15" title="15"># Now you can temporarily add your backup image as a block device:</a>
<a class="sourceLine" id="cb4-16" title="16">drive_add 0 if=none,id=temphd0,format=qcow2,file=/sdcard/backup.qcow2</a>
<a class="sourceLine" id="cb4-17" title="17"></a>
<a class="sourceLine" id="cb4-18" title="18"># And overwrite the original HDD image:</a>
<a class="sourceLine" id="cb4-19" title="19">drive_backup -f -c temphd0 /data/user/0/alpine.term/files/run/alpine-linux-hdd.qcow2 qcow2</a></code></pre></div>
<p>Wait until job finishes (command ‘info block-jobs’) and then restart Alpine Term.</p>
<h4 id="shell">Shell</h4>
<h5 id="list-of-common-shell-commands">List of common shell commands</h5>
<table>
<colgroup>
<col style="width: 53%"></col>
<col style="width: 46%"></col>
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Command</th>
<th style="text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;"><code>apk add &lt;pkg&gt;</code></td>
<td style="text-align: left;">Install the specified package.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>apk del &lt;pkg&gt;</code></td>
<td style="text-align: left;">Uninstall the specified package.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>apk upgrade</code></td>
<td style="text-align: left;">Upgrade the installed packages.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>apk info</code></td>
<td style="text-align: left;">List the installed packages.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>cat &lt;file&gt;</code></td>
<td style="text-align: left;">Print content of the specified file.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>cd &lt;dir&gt;</code></td>
<td style="text-align: left;">Navigate to the specified directory.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>chgrp &lt;group&gt; &lt;path&gt;</code></td>
<td style="text-align: left;">Change the group of the specified file or directory.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>chmod &lt;mode&gt; &lt;path&gt;</code></td>
<td style="text-align: left;">Change access mode of the specified file or directory.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>chown &lt;ownership&gt; &lt;path&gt;</code></td>
<td style="text-align: left;">Change ownership of the specified file or directory.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>cp &lt;src&gt; &lt;dst&gt;</code></td>
<td style="text-align: left;">Copy file from the specified source to destination.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>date</code></td>
<td style="text-align: left;">Print the current date and time.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>df -h</code></td>
<td style="text-align: left;">Show the current disk space usage.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>dmesg</code></td>
<td style="text-align: left;">Print the kernel log.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>file &lt;path&gt;</code></td>
<td style="text-align: left;">Detect a type of the specified file.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>free -h</code></td>
<td style="text-align: left;">Show RAM usage.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>grep &lt;pattern&gt; &lt;file&gt;</code></td>
<td style="text-align: left;">Find occurrences of the specified pattern in a file.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>gunzip &lt;file.gz&gt;</code></td>
<td style="text-align: left;">Decompress the given file.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>gzip &lt;file&gt;</code></td>
<td style="text-align: left;">Compress the given file.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>hostname</code></td>
<td style="text-align: left;">Print the current system host name.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>id</code></td>
<td style="text-align: left;">Print the user and group IDs associated with current user.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>ifconfig</code></td>
<td style="text-align: left;">Show the information about active network interfaces.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>kill -9 &lt;pid&gt;</code></td>
<td style="text-align: left;">Kill the process with specified PID.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>ln -s &lt;src&gt; &lt;dest&gt;</code></td>
<td style="text-align: left;">Create a symbolic link between the specified source and destination.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>ls</code></td>
<td style="text-align: left;">List files in the current directory.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>ls &lt;dir&gt;</code></td>
<td style="text-align: left;">List files in the specified directory.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>man &lt;command&gt;</code></td>
<td style="text-align: left;">Open manual for the specified command.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>mkdir -p &lt;path&gt;</code></td>
<td style="text-align: left;">Create directory at the specified path.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>mv &lt;src&gt; &lt;dst&gt;</code></td>
<td style="text-align: left;">Move file or directory from the specified source to destination. Can be used to rename files.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>nano &lt;file.txt&gt;</code></td>
<td style="text-align: left;">Edit specified text file with Nano editor.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>netstat -tun</code></td>
<td style="text-align: left;">Show the active network connections.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>netstat -tuln</code></td>
<td style="text-align: left;">Show the listening sockets (servers).</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>poweroff</code></td>
<td style="text-align: left;">Shut down the machine.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>ps aux</code></td>
<td style="text-align: left;">Show all system processes.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>pwd</code></td>
<td style="text-align: left;">Print the path of the current working directory.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>reboot</code></td>
<td style="text-align: left;">Reboot the operating system.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>rm -rf &lt;path&gt;</code></td>
<td style="text-align: left;">Delete the specified file or directory.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>reset</code></td>
<td style="text-align: left;">Reset the terminal.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>resize</code></td>
<td style="text-align: left;">Resize the console.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>tar cf file.tar &lt;dir&gt;</code></td>
<td style="text-align: left;">Create a tar archive of the specified directory.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>tar xf file.tar</code></td>
<td style="text-align: left;">Extract the specified tar archive.</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>uname -a</code></td>
<td style="text-align: left;">Show system host name, kernel version and CPU architecture.</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>wget &lt;url&gt;</code></td>
<td style="text-align: left;">Download file from the specified URL.</td>
</tr>
</tbody>
</table>
<p>For more details about shell usage and scripting you can read the <a href="doc/bash-advanced.html">Advanced Bash-Scripting Guide</a>. Although this guide is for Bash shell, most of the tips apply to other shells as well.</p>
<p>Also read the <a href="https://wiki.alpinelinux.org">Alpine Linux Wiki</a> for details about administering Alpine systems.</p>
<h4 id="using-custom-disk-images">Using custom disk images</h4>
<p>You can have additional CD-ROM or HDD image. To do so place your ISO or QCOW2 file on <a href="#sharing-files-between-host-and-vm">shared storage</a> into this directory:</p>
<div class="sourceCode" id="cb5" data-startFrom="1"><pre class="sourceCode numberSource numberLines"><code class="sourceCode"><a class="sourceLine" id="cb5-1" title="1">/storage/self/primary/Android/data/alpine.term/files</a></code></pre></div>
<p>Ensure that image file names are ‘cdrom.iso’ for CD-ROM and ‘hdd.qcow2’ for HDD respectively. Note that this way allows you to have only one image of each type.</p>
<p><em>This method is deprecated on Android 11+ due to storage changes.</em></p>
<p>Another variant how to add a disk image would be the use of the monitor console. Here is an example of how to add a custom CD-ROM image:</p>
<div class="sourceCode" id="cb6" data-startFrom="1"><pre class="sourceCode numberSource numberLines"><code class="sourceCode"><a class="sourceLine" id="cb6-1" title="1"># Regular way with just ISO file.</a>
<a class="sourceLine" id="cb6-2" title="2">drive_add 0 if=none,media=cdrom,id=cd1,file=/sdcard/mycd.iso</a>
<a class="sourceLine" id="cb6-3" title="3"></a>
<a class="sourceLine" id="cb6-4" title="4"># Or remote image accessible over HTTP:</a>
<a class="sourceLine" id="cb6-5" title="5">drive_add 0 if=none,media=cdrom,id=cd1,file=https://example.com/cdrom.iso</a>
<a class="sourceLine" id="cb6-6" title="6"></a>
<a class="sourceLine" id="cb6-7" title="7"># NBD also works:</a>
<a class="sourceLine" id="cb6-8" title="8">drive_add 0 if=none,media=cdrom,id=cd1,file=nbd://192.168.1.10:1024/cdrom</a>
<a class="sourceLine" id="cb6-9" title="9"></a>
<a class="sourceLine" id="cb6-10" title="10"># Once block device is added, create a CD-ROM device:</a>
<a class="sourceLine" id="cb6-11" title="11">device_add scsi-cd,id=scsi-cd1,drive=cd1</a></code></pre></div>
<h4 id="sharing-files-between-host-and-vm">Sharing files between host and VM</h4>
<p>The Alpine Term application maintains a directory on Android storage for sharing files between host and virtual machine. Inside the virtual machine this directory is mounted at ‘/mnt/shared’ by <code>fstab</code> and on the host it is usually accessible at</p>
<div class="sourceCode" id="cb7" data-startFrom="1"><pre class="sourceCode numberSource numberLines"><code class="sourceCode"><a class="sourceLine" id="cb7-1" title="1">/storage/self/primary</a></code></pre></div>
<p>Sharing files may not be possible through this way if host shared storage is not available. That are rare cases however, like when shared storage is actually removable SD-CARD which was ejected.</p>
<p><strong>Warning</strong>: if you want to uninstall the Alpine Term, do not forget to move files from the host shared directory to a different place. Otherwise, all its data will be lost.</p>
<h4 id="shutting-down-the-vm">Shutting down the VM</h4>
<p>You can shut down the virtual machine and exit application with these ways:</p>
<ul>
<li>Executing command ‘quit’ in QEMU monitor for immediate exit. May leave HDD file system in an inconsistent state.</li>
<li>Executing command ‘system_powerdown’ in QEMU monitor to initiate OS shut down through ACPI.</li>
<li>Executing command ‘poweroff’ in OS shell.</li>
</ul>
<p>If application got frozen and does not respond for some reason, you will need to force stop it through Android OS settings.</p>
<hr />
<p style="text-align:center;">
<font size="1dp"><i>Alpine Term by Leonid Pliushch</i></font>
</p>
</body>
</html>
